Pull Request Overview

This PR adds a comprehensive developer guide for working with flowey, the OpenVMM project's automation framework. The guide introduces core concepts, architectural patterns, and best practices to help contributors understand and work with flowey effectively.

Key changes:

• Added detailed documentation explaining flowey's two-phase execution model and backend abstraction
• Documented core concepts including pipelines, artifacts, nodes, and variables
• Included practical examples and design patterns for common workflows

This is already useful, thanks! I learned a few things reading through this.

Overall, my commentary is primarily stylistic, since the content either already matches what I know, or is telling me things I don't know.

My general style feedback is:

• Keep the Guide conceptual, and move code and code examples into the rust docs. We publish those as part of the build, so you can even link to them directly from this guide.
• Use ```admonish rather than the existing Note (for here and other important places)

Besides the semantic questions that I asked, I also wonder:

• Do we have code layout or naming conventions? (e.g. _jobs folder, artifact_*.rs for artifact definitions)
• How much processing should I do in an artifact? Is it just a record of files? Or should I ever do a transformation in one?

@smalis-msft sent this my way, and given that I didn't end up sending in flowey docs before I left msft (tbf, I had a very short runway prior to leaving!), I figured the least I could do is chime in with some comments here.

maybe the most important feedback is that you def want to invert the presentation of a lot of the concepts in the guide. start from the base building blocks (steps), go into how those compose into nodes (with requests), how those get coalesced into jobs, and how those become pipelines (with a discussion on artifacts). As written today - this guide is really hard to follow, unless you are willing to read this whole thing multiple times.

also, having a high-level overview discussing the "why" behind flowey seems important to set the stage for the rest of the discussion. i.e: talk about how traditional back + YAML based pipelines are impossible to maintain, rely heavily on non-local reasoning and global state, can't be run locally / ported between platforms, etc...

Pull Request Overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated 1 comment.